<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>elasticsearch-migrate | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="commands.html" title="Command line tools">
<link rel="prev" href="elasticsearch-keystore.html" title="elasticsearch-keystore">
<link rel="next" href="node-tool.html" title="elasticsearch-node">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="commands.html">Command line tools</a></span>
»
<span class="breadcrumb-node">elasticsearch-migrate</span>
</div>
<div class="navheader">
<span class="prev">
<a href="elasticsearch-keystore.html">« elasticsearch-keystore</a>
</span>
<span class="next">
<a href="node-tool.html">elasticsearch-node »</a>
</span>
</div>
<div class="chapter xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="migrate-tool"></a>elasticsearch-migrate<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/commands/migrate-tool.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p><span class="Admonishment Admonishment--change">
[<span class="Admonishment-version u-mono u-strikethrough">7.2.0</span>]
<span class="Admonishment-detail">
Deprecated in 7.2.0. This tool is deprecated. Use the native realm directly.
</span>
</span></p>
<p>The <code class="literal">elasticsearch-migrate</code> command migrates existing file-based users and roles
to the native realm. From 5.0 onward, you should use the <code class="literal">native</code> realm to
manage roles and local users.</p>
<h3>
<a id="_synopsis_4"></a>Synopsis<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/commands/migrate-tool.asciidoc">edit</a>
</h3>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">bin/elasticsearch-migrate
(native (-U, --url &lt;url&gt;)
[-h, --help] [-E &lt;KeyValuePair&gt;]
[-n, --users &lt;uids&gt;] [-r, --roles &lt;roles&gt;]
[-u, --username &lt;uid&gt;] [-p, --password &lt;password&gt;]
[-s, --silent] [-v, --verbose])</pre>
</div>
<h3>
<a id="_description_4"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/commands/migrate-tool.asciidoc">edit</a>
</h3>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When migrating from Shield 2.x, the <code class="literal">elasticsearch-migrate</code> tool should be
run prior to upgrading to ensure all roles can be migrated as some may be in a
deprecated format that X-Pack cannot read. The <code class="literal">migrate</code> tool is available in
Shield 2.4.0 and higher.</p>
</div>
</div>
<p>The <code class="literal">elasticsearch-migrate</code> tool loads the existing file-based users and roles
and calls the user and roles APIs to add them to the native realm. You can
migrate all users and roles, or specify the ones you want to migrate. Users and
roles that already exist in the <code class="literal">native</code> realm are not replaced or
overridden. If the names you specify with the <code class="literal">--users</code> and <code class="literal">--roles</code> options
don’t exist in the <code class="literal">file</code> realm, they are skipped.</p>
<h3>
<a id="migrate-tool-options"></a>Parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/commands/migrate-tool.asciidoc">edit</a>
</h3>
<p>The <code class="literal">native</code> subcommand supports the following options:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">-E &lt;KeyValuePair&gt;</code>
</span>
</dt>
<dd>
Configures a setting.
</dd>
<dt>
<span class="term">
<code class="literal">-h, --help</code>
</span>
</dt>
<dd>
Returns all of the command parameters.
</dd>
<dt>
<span class="term">
<code class="literal">-n</code>, <code class="literal">--users</code>
</span>
</dt>
<dd>
Comma-separated list of the users that you want to migrate. If this parameter is
not specified, all users are migrated.
</dd>
<dt>
<span class="term">
<code class="literal">-p</code>, <code class="literal">--password</code>
</span>
</dt>
<dd>
Password to use for authentication with Elasticsearch.
</dd>
<dt>
<span class="term">
<code class="literal">-r</code>, <code class="literal">--roles</code>
</span>
</dt>
<dd>
Comma-separated list of the roles that you want to migrate. If this parameter is
not specified, all roles are migrated.
</dd>
<dt>
<span class="term">
<code class="literal">-s, --silent</code>
</span>
</dt>
<dd>
Shows minimal output.
</dd>
<dt>
<span class="term">
<code class="literal">-U</code>, <code class="literal">--url</code>
</span>
</dt>
<dd>
Endpoint URL of the Elasticsearch cluster to which you want to migrate the
file-based users and roles. This parameter is required.
</dd>
<dt>
<span class="term">
<code class="literal">-u</code>, <code class="literal">--username</code>
</span>
</dt>
<dd>
Username to use for authentication with Elasticsearch.
</dd>
<dt>
<span class="term">
<code class="literal">-v, --verbose</code>
</span>
</dt>
<dd>
Shows verbose output.
</dd>
</dl>
</div>
<h3>
<a id="_examples_7"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/commands/migrate-tool.asciidoc">edit</a>
</h3>
<p>Run the <code class="literal">elasticsearch-migrate</code> tool when X-Pack is installed. For example:</p>
<div class="pre_wrapper lang-sh">
<pre class="programlisting prettyprint lang-sh">$ bin/elasticsearch-migrate native -U http://localhost:9200 -u elastic
-p x-pack-test-password -n lee,foo -r role1,role2,role3,role4,foo
starting migration of users and roles...
importing users from [/home/es/config/shield/users]...
found existing users: [test_user, joe3, joe2]
migrating user [lee]
{"user":{"created":true}}
no user [foo] found, skipping
importing roles from [/home/es/config/shield/roles.yml]...
found existing roles: [marvel_user, role_query_fields, admin_role, role3, admin,
remote_marvel_agent, power_user, role_new_format_name_array, role_run_as,
logstash, role_fields, role_run_as1, role_new_format, kibana4_server, user,
transport_client, role1.ab, role_query]
migrating role [role1]
{"role":{"created":true}}
migrating role [role2]
{"role":{"created":true}}
role [role3] already exists, skipping
no role [foo] found, skipping
users and roles imported.</pre>
</div>
<p>Additionally, the <code class="literal">-E</code> flag can be used to specify additional settings. For example
to specify a different configuration directory, the command would look like:</p>
<div class="pre_wrapper lang-sh">
<pre class="programlisting prettyprint lang-sh">$ bin/elasticsearch-migrate native -U http://localhost:9200 -u elastic
-p x-pack-test-password -E path.conf=/etc/elasticsearch</pre>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="elasticsearch-keystore.html">« elasticsearch-keystore</a>
</span>
<span class="next">
<a href="node-tool.html">elasticsearch-node »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
